# !/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
===========================
@Time : 2022/8/23 0023 0:42
@Author : 测试开发工程师
@File : 9. Flask RESTX 集成 Swagger.py
@Software: PyCharm
============================
"""

"""
# ==================================================================================

一：namespace 的使用
    解决路由分类（更清晰）
    
Flask-RESTX namespace 的使用
    1. 定义 Namespace 实例
    2. 为类添加装饰器 @namespace.route('')  。 控制子路由
    3. 为命名空间指定访问资源路径  api.add_namespace(case_ns,'/case')
    

二：Flask-RESTX 中 Swagger 接口文档配置
    第一种：使用@api.doc() 或者 @namespace.doc装饰请求方法。例如： @api.doc(params={'id':'An ID'})
    第二种 [推荐] ： 使用 解析器 ： parser = api.parser() 配合 @api.expect(parser) 装饰器实现入参的检验和传入

swagger 界面组成
    API 版本号   api = Api(app, version="2.0")
    BaseUrl      hello_ns = Namespace('demo', description='demo学习')
    主体

api.parser() 用法
    get_parser.add_argument('id',type=int,location="args")
    
    格式： api.parser().add_argument(参数名，关键字参数)
    第一个参数是参数名
    后面是关键字传参，常用的关键字有：   
        type : 类型
        required : 约束控制，required=True，是否为必填项
        choices: 枚举参数
        location : 对应 request 对象中的属性

    常用的关键字参数：
        参数名     参数值
        type       int, bool, float, string, FileStorage
        required   True/False
        choices    枚举
        location   args（get 常用）, post 常用：  form, json, files

============================   json 和  file 不能同时存在, form 和 json 不能同时存在  =============================
    get请求  location 一般用 args 处理
    post请求 location 一般用 json 处理
       location 常用 files/form/choice格式
    delete请求 location 一般用 args 和 json
    put 请求 location一般用  ： args 和 json

"""

from flask import Flask
from flask_restx import Resource, Api

app = Flask(__name__)
api = Api(app)


# 接口路径定义到类上，对应的不同请求操作创建不同的方法
@api.route('/case')
class TestCase(Resource):
    # restful 风格的 get 方法
    def get(self):
        return {'code': 0, 'msg': 'get success'}

    # restful 风格的 post 方法
    def post(self):
        return {'code': 0, 'msg': 'post success'}
